Руководство для кузнецов
Перед прочтением этой статьи, сначала прочтите: * Вклад (раздел «Программисты (Web & Mobile)») * Установка Habitica локально Стек технологий Ниже перечислены технологии, которые использует Habitica. Вам не требуется владеть всеми ими или даже частью из них, чтобы помогать нам! Некоторые ссылки ведут на высококачественный обучаемый материал. * Сервер: ** ExpressJS ** Node.js *** С чего начать изучение Node.js *** nodeschool - упоминается в статье выше, но особенно крут начальный уровень учебного курса по node ** MongoDB ** MongooseJS ** Bower ** Gulp * Клиент: ** AngularJS *** Обучение Angular.js - Обучающие видео с упражнениями. Вы, вероятно, обнаружите, что одних видео будет достаточно, чтобы понять код Habitica на AngularJS, хотя конечно упражнения также будут полезны. *** Изучаем Angular - Бесплатные интерактивные уроки. ** Boostrap ** Jade ** Stylus * Тестирование: ** Karma ** Mocha ** Jasmine (используется только для end-to-end тестирования работы статической главной страницы) ** Selenium (используется только для end-to-end тестирования работы статической главной страницы) * Сервисы: ** New Relic ** Heroku ** AWS ** Amplitude * Другое: ** iOS ** Android ** git и GitHub *** Pro Git - Отличный ресурс. Вам будет гораздо комфортнее работать с git, если вы не спеша прочитаете его. *** git-it - прокрутите вниз, чтобы узнать больше. Является частью учебной программы nodeschool, а также веселый и интерактивный способ изучить git и GitHub. __TOC__ Советы по работе с локальной установкой После того, как вы установили Habitica локально, здесь перечислена пара полезных советов к вашей установке. Быстрый перезапуск сервера После запуска вашего сервера (например, run npm server), конец вывода консоли будет выглядеть как-то так: Running "nodemon:dev" (nodemon) task nodemon v1.2.1 nodemon to restart at any time, enter `rs` nodemon watching: *.* nodemon starting `node ./website/src/server.js` info: Express server listening on port 3000 info: Connected with Mongoose Строки nodemon означают, что после того, как вы сделаете какие-либо изменения в коде, который вы хотели бы проверить, вы можете просто ввести: rs и затем нажать для перезапуска сервера. Это гораздо быстрее, чем выход и повторный запуск npm server. Меню отладки Следующее меню находится в нижней части каждой страницы вашей локальной установки, и может быть использовано для быстрого вызова определенных ситуаций, делая тестирование кода проще. Git Здесь написан маленький урок как форкнуть репозиторий «habitrpg», создать ветки для новых фич, и делать пул-реквесты. Форк и клонирование Habitica Самый простой способ – зайти на страницу репозитория «habitrpg» и нажать кнопку «Fork». Затем выполнить git clone в своём репозитории. Либо сделать это: git clone https://github.com/HabitRPG/habitrpg.git напрямую, затем (и обратите внимание, что вам следует поменять YourUsername на ваше имя пользователя на GitHub'е): cd habitrpg git remote set-url origin https://github.com/''YourUsername/habitrpg.git И наконец: git push для обновления вашего форка. Настройка отслеживаемой удаленной ветки Следующим шагом будет отслеживание репозитория «habitrpg», таким образом мы сможем легко загружать в наш форк последние изменения. Так как '''origin' – URL нашего форка, мы создадим ещё одну удаленную ветку upstream для «habitrpg»: git remote add upstream https://github.com/HabitRPG/habitrpg.git Теперь, каждый раз, когда мы захотим получить свежий код из «habitrpg», мы напишем: git fetch upstream Перемещение (rebase) ветки Когда вы захотите обновить вашу локальную ветку, вам потребуется переместить её из ветки upstream. Давайте обновим develop: git checkout develop git fetch upstream git rebase upstream/develop git push # to update your fork Если вы получили ошибку fatal: 'upstream' does not appear to be a git repository, то убедитесь, что основной репозиторий добавлен как upstream: git remote add upstream https://github.com/HabitRPG/habitrpg.git После обновления, могут понадобятся новые пакеты node в проекте, т.ч. не забудьте ещё раз выполнить: sudo npm install Примечание: Если вы собираетесь работать над фичей, которая была начата кем-то другим, и ещё не была слита (merge) с upstream, вы можете проделать шаги, как показано в 2 и 3, чтобы загрузить их коммиты: Давайте предположим, что пользователь 'Fandekasp' написал новую фичу 'add_theme', которая ожидает пул-реквеста в 'upstream/audio'. У вас тоже имеется форк 'upstream/audio' и вы захотели получить изменения, сделанные Fandekasp'ом прямо сейчас. git remote add fandekasp https://github.com/Fandekasp/habitrpg.git git fetch fandekasp git rebase fandekasp/add_themes Создание новой фичи Теперь, вы захотели начать работу над новой задачей, и запул-реквестить её. Сначала, вам нужно решить в какой ветке начать работу. Выполните git branch -r, чтобы увидеть список удалённых веток. Выберите подходящую ветку в зависимости от того, над какой задачей вы хотите работать. Давайте предположим, что вы решили начать разрабатывать свою задачу в ветке develop. Для этого сделайте следующее: git checkout -b relevant_branch_name upstream/develop Затем вы можете выполнить git push, чтобы отправить его в ваш форк. Запись коммитов При разработке кода, рекомендуется делать маленькие регулярные коммиты, которые легче просматривать, чем большой. Это также облегчает жизнь разработчикам: отказаться или отредактировать какой-нибдуь конкретный коммит, который требует правки. Например, вы делаете коммит, посвящённый тестам, а потом ещё один с правками для интерфейса, один для логики и один для переводов. Если вы делаете правки в несколько дней, убедитесь, что вы переместили вашу ветку, чтобы правильно обновлять свой код. При возниковении каких-либо конфликтов, вы возможно просто захотите воспользоваться версией upstream: git rebase -Xours upstream/develop Пул-реквест Когда вы закончите работу над своим кодом, или он будет завершён наполовину, но вы всё равно хотите сделать пул-реквест (например, для получения критики), запушьте ваш код из ветки в свой форк. Теперь откройте https://github.com/YourUsername/habitrpg.git, и вы увидите кнопку «Pull Request». Когда вы сделаете пул-реквест, убедитесь, что слияние будет выполнено с правильной веткой. Часто по умолчанию указывается upstream/develop, даже если вы создали свою ветку из другой. Перед отправкой пул-реквеста, вы можете запустить тесты, чтобы проверить, если что-то работает не должным образом.. Другой способ – воспользоваться инструментом hub (установите его с помощью вашего менеджера пакетов), затем выполните hub pull-request из вашей ветки. Проблемы Вы попытались сделать перемещение и теперь у вас появилось несколько новых и бесполезных коммитов в вашей ветке. Не беспокойтесь, вот пара решений, как выбраться из этой путаницы: Cherry-pick Первое решение – открыть окно и выполнить в нём git log, чтобы вывести список всех ваших коммитов с их хэш-идентификаторами (длинными строками, состоящими из цифр и букв). Теперь, открыв другое окно, вы можете выполнить git reset --hard HEAD~1 (если вам нужно удалить один единственный коммит, иначе HEAD~nb_of_commits). Если вы удалили слишком много коммитов, то просто выполните git pull ещё раз из вашего форка. Затем скопируйте хэши тех коммитов, которые вы бы хотели повторно добавить поверх вашей ветки (из окна, в котором вы выполняли git log ранее). Например, git cherry-pick ee1768b7e2c0bcee9eff1a45be1e3543fac0687b Это повторно добавит коммит ee1768b7e2c0bcee9eff1a45be1e3543fac0687b поверх HEAD. Stash Если ваша попытка выполнить git push не увенчалась успехом из-за того, что HEAD удалённой ветки различается с вашим (такое случается, когда над одной веткой работает несколько человек и они пушат в ту же удалённую ветку), ни в коем случае не делайте git pull. Вместо этого, сделайте так: git reset --soft HEAD~n_local_commits_ahead git stash git pull git stash pop git commit -am "message" Работа с habitrpg-shared ВНИМАНИЕ! Репозиторий «habitrpg-shared» устарел. Файлы из него были перемещены в подкаталог common репозитория «habitrpg», а все действия, которые вы делали при работе с «habirpg-shared», можете делать там. Если вы увидите какие-либо инструкции, которые указывают на использование habitrpg-shared, пожалуйста сообщите о них в гильдию Aspiring Coders, и, если потребуется, попросите разъяснений. MongoDB Краткие советы для новых разработчиков, чтобы научиться пользоваться базой данных. В командах ниже знак «$» указывает на использование командной оболочки Unix или Windows или Git, а знак «>» указывает на использование командной оболочки mongo. Вводите текст только после этих знаков. Доступ к командной оболочке Запустите командную оболочку mongo, затем выберите базу данных: $ mongo > show dbs > use habitrpg Также то же самое можно сделать напрямую запустив командную оболочку вместе с существующей базой данных: $ mongo habitrpg Использование командной оболочки Просмотр коллекций в базе данных («users», «groups», и др.): > show collections Поиск тестового пользователя и изучение его данных. Из настроек localhost скопируйте идентификатор пользователя, и затем выполните эту команду: > db.users.find({_id: '85b007a2-b5b9-4bb4-8b82-e4567edb4919'})0 Хотите посмотреть только настройки? > db.users.find({_id: '85b007a2...'})0.preferences Чтобы обновить что-либо для вашего пользователя, используйте метод update вместе с $set. Например, изменение вашего профиля blurb: > db.users.update({_id: '85b007a2...'}, {$set: {'profile.blurb':'test'}}) Дать себе 10 самоцветов (это также можно сделать через «Меню отладки» в правой нижней части страницы): > db.users.update({_id: '85b007a2...'}, {$set: {'balance':10}}) Получить права админа (у вас появятся дополнительные возможности в Зале): > db.users.update({_id: '85b007a2...'}, {$set: {'contributor': {'admin':1}}}) Дать себе непокупаемые квестовые свитки (например, квесты ограниченного выпуска): db.users.update({_id: '85b007a2...'}, {$set: {'items.quests': {"egg":2,"dilatory":1,"stressbeast":1,"basilist":1,"evilsanta":1,"evilsanta2":1}}}) Это выдаст пользователю 2 свитка «Поиски яиц» и по одному свитку остальных 5 квестов. Обратите внимание, что таким образом удалятся все другие свитки пользователя, которые он выполняет, но их можно будет добавить тем же способом (соответствующие ключи можно найти в content.coffee) или купить позже в магазине. Создание аккаунта пользователя с данными настоящего аккаунта Экспортируйте ваши данные пользователя используя API адрес GET /user, и импортируйте их локально используя команды MongoDB, например, db.collection.insert(). Это может быть более быстрый способ создать локальный аккаунт, предварительно заполнив его задачами, снаряжением и т.д. Ваш аккаунт необходимо будет импортировать в коллекцию users, но эта коллекция не будет существовать в mongo до тех пор, пока вы не создадите аккаунт в своей локальной копии. Это можно сделать проще, запустив локальную копию и создав тестовый аккаунт, а затем вставить ваш настоящий аккаунт в коллекцию users. Миграции Некоторые изменения сайта Habitica требуют существующих аккаунтов пользователей для модификации (например, чтобы присвоить значение по умолчанию новой настройке для всех пользователей). Такие изменения базы данных делаются с помощью скриптов миграций, которые содержат JavaScript, соединяющийся с базой данных и делающий модификации. Все скрипты миграций лежат в migrations/. Почитайте и используйте их, как примеры, чтобы написать свои собственные. Скрипты, которые были отредактированы недавно, вероятно, содержат более лучший код, чем в старых скриптах. Чтобы протестировать скрипт миграции, выполните: $ mongo habitrpg migrations/name_of_script.js Советы и лучшие практики по Angular/Node/Jade Связывание данных и шаблоны условий При работе с шаблонами Jade, вы можете увидеть атрибуты элементов, такие как ng-class, ng-show или ng-if. Это привязки, которые используются для преобразования данных модели элементов для отображения, которые являются частью AngularJS. Эти привязки можно использовать для определения стилей или отображения на основе условий. Вы также можете заметить другие такие же атрибуты, например, bo-class или bo-if... так в чём же разница? Привязки начинающиеся с «ng» являются частью AngularJS и полностью динамичны. Это означат, что всякий раз, когда что-то изменяется в приложении, Angular проверяет все эти условные привязки снова и снова. Очевидно, что это является проблемой для производительности. Иногда данные, используемые для расчёта условий изменяются редко, если вообще изменяются. В таком случае, мы можем сделать статическую привязку, применив библиотеку Bindonce. Это схожие привязки, но они проверяются только при первом запуске приложения. По возможности, этот способ связывания должен быть предпочтительнее до тех пор, пока данные не изменятся. Директивы Bindonce следует использовать только, если следующее правило верно: данные модели, применяемые для условий не изменяются в течение сессии, или изменяются достаточно редко, т.ч. не разумно ожидать от пользователя обновления страницы. Если нет, используйте традиционные привязки. Если вы не можете решить или не поняли, что только что прочитали, тогда используйте атрибуты ng-<...>. Переводимые строки (файлы локалей) Добавление переводимых строк Если вам требуется добавить новую переводимую строку в какой-то шаблон, она должна быть записана в jade-файл следующим образом: env.t("stringLabel") Затем, в директории common/locales/ru, отредактируйте json-файлы, добавив в них новую строку: "lastLabel": "Добавить запятую в конец этой строки", "stringLabel": "Заголовок строки" } Ни в коем случае не обновляйте json-файлы в других директориях common/locales; переводы контролируются на Transifex. Чтобы протестировать строку: * остановите npm, если он запущен ( + ) * выполните npm start Редактирование переводимых строк Переводимые строки находятся в файлах директории common/locales/ru. Каждая строка состоит из ключа и текста, например: "clearAll": "Удалить все сообщения", Если вам требуется изменить переводимую строку, не изменяйте ключ строки, если нет очень веской причины для этого. Например, если вам нужно изменить «удалить все сообщения» на «стереть все сообщения,» вы не должны изменять ключ «clearAll» на «deleteAll». Дело в том, что ключ («clearAll») может использовать во многих местах по всему коду Habitica, и изменение ключа приведёт к тому, что от вас может потребовать сделать ненужные изменения в коде. Кроме того, ключи, которые используются в переводимых строках английского языка также используются во всех остальных языках в common/locales. Когда английский текст изменяется без смены ключа, другие языки продолжают использовать существующие переводы для оригинальной английского текста до тех пор, пока переводчики не решат обновить перевод. Обычно, так оно и происходит, т.к. существующие переводы, как правило, достаточно хороши, чтобы их менять. Однако, если вы измените ключ, а также текст, все существующие переводы не будут использоваться, потому что языковые файлы не содержат нового ключа. Это означает, что люди, использующие другие языки, кроме английского, не увидят новый английский текст до тех пор, пока переводчики не найдут время, чтобы отредактировать ключи строк на новый ключ. Тесты Habitica имеет набор тестов, которые можно запустить вручную или автоматически, что помогает нам избежать багов. Всякий раз, когда на GitHub приходит пул-реквест, Travis CI запускает все тесты. Любые неудачные тесты рассматриваются, чтобы понять, является ли новый код проблемным. Большая часть нового кода должна иметь тесты перед тем, как они будут объединены с кодовой базой, однако админы Habitica будут очень рады помочь вам с написанием таких тестов, или написать их за вас, если вы по какой-то причине не можете это сделать. Не бойтесь отправлять пул-реквест без тестов, особенно, если вы не особо понимаете в чём смысл процесса тестирования, но не забывайте о том, что ваша заявка не будет принята до тех пор, пока админы не напишут тесты. Чтобы запустить тесты из вашей локальной установки, перейдите в корневой каталог и выполните npm test. Это алиас для node_modules/.bin/gulp test, который подготовит тестовую среду и запустит набор тестов. Чтобы запустить какой-то один тест из вашей локальной установки, выполните mocha test/SUBDIRECTORY/NAME_OF_TEST.coffee. Другое Несколько полезны команд. Поиск кода В консоли, введите: grep -R "STRING" * Чтобы найти строку STRING во всех файлах в текущем каталоге и его под-каталогах. Если вы хотите выполнить поиск без учёта регистра (например, STRING или String или string), добавьте флаг '-i': grep -iR "STRING" * Часто вы хотите найти все файлы, содержащие какое-то ключевое слово, чтобы определить, какие файлы нужно отредактировать при добавлении/изменении какой-либо фичи. Команда grep также принимает регулярное выражение в качестве шаблона для поиска: grep -R "REGEX" * Поиск и замена Вот команда на Perl'е: perl -e "s/FROM/TO/g" -pi $(find . -name "*.js") Замените FROM на строку, которую вы хотите заменить, а TO – на строку, которой вы хотите заменить первую строку. Обратите внимание, что этот пример заменит строки только в JavaScript-файлах (расширение .js), но вы можете указать другие расширения, если хотите. Если вы хотите заменить все строки, но не их множественное число или другие строки, содержащие эту под-строку (например, заменить weapon из TEST, но не weapons: perl -e 's/weapon\b/TEST/g' -pi * Если вы хотите удалить все строки в JS-файлах, содержащих какое-то ключевое слово: perl -ni -e 'print unless /keyword/' -pi $(find . -name "*.js") Эти команды особенно полезны при работе над переводом. Тестирование интерфейса Swagger API локально Habitica имеет собственный интерфейс API: https://habitrpg.com/static/api, который использует базу данных и код из продакшена. Когда вы установите Habitica локально, вы можете протестировать локальную версию этого интерфейса: http://localhost:3000/static/api. Если ваша версия config.json была создана давно и вы имеете не самые свежие данные в нём, вам возможно потребуется отредактировать config.json и изменить в нём строку BASE_URL на "BASE_URL":"http://localhost:3000", а затем отменить и перезапустить команду npm start. Предпочитаемые настройки Habitica имеет предпочитаемые настройки для пользователей, чтобы настроить поведение веб-сайта. Вы можете добавлять свои настройки по необходимости. Однако, не добавляйте настройки, которые будут полезны лишь для малой части пользователей, или настройки полезные вам; вместо этого, выберите настройки, которым большинство пользователей скорее всего будут рады. Слишком много предпочтений делает экран настроек раздутым и загроможденным, и повышает запутанность. Если вы не уверены, подходит ли та или иная предпочитаемая настройка, вы можете обсудить её в гильдии Aspiring Coders или в соответствующей GitHub обсуждении или пул-реквесте. Классный совет для хранения настроек В git-обсуждении новой предпочитаемой настройки пользователя прозвучал такой совет: Новые предпочитаемые настройки можно добавлять в website/src/models/user.js, тогда база данных автоматически «заберёт» их (даже если требуется настройка БД). Раздел «Информация для разработчиков» на других страницах вики В нижней части некоторых страниц вики, вы увидите разделы Информация для разработчиков. Они содержат полезные советы для кузнецов, связанными с контентом этой страницы. Информация скрыта за спойлер в стиле переключателя «скрыть/показать», чтобы он не загромождал страницу для нетехнических пользователей. Разделы используют шаблоны и , чтобы обеспечить правильное форматирование, название кнопок и остальной текст. Чтобы увидеть как это работает, откройте любую страницу, где присутствует этот раздел, в исходном редакторе. Чтобы увидеть список всех страниц, где есть этот раздел, используйте инструмент «Ссылки сюда» для шаблона «Start». Если вы хотите, чтобы раздел «Информация для разработчиков» по умолчанию был виден: * создайте учетную запись на Wikia, если вы этого ещё не сделали * отредактируйте ваш личный Wikia.css, который находится по адресу http://ru.habitica.wikia.com/wiki/Участник:ВАШЕ_ИМЯ_ПОЛЬЗОВАТЕЛЯ/wikia.css * вставьте эти строки в ваш CSS-файл: /* Force all "Information for Developers" sections to always be visible */ .habitrpg-InfoForDevs { display:block !important; } .habitrpg-InfoForDevs-hideIfDev { display:none; } Пример того, как это будет выглядеть, можно посмотреть на http://habitrpg.wikia.com/wiki/User:LadyAlys/wikia.css. en:Guidance_for_Blacksmiths Категория:Вклад Категория:Контент